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The goal of automatic documentation of computer programs is to establish procedures, 
called documentation programs, that can be implemented by computer programs. These 
documentation programs may be divided into two categories; postmortem and develop- 
mental documentation programs. In the former case, a computer program is presented as 
input for documentation without any preparation; in the latter case, the program to be 
documented must be developed so that it contains information necessary for the 
documentation. 

This paper is concerned only with the development documentation programs. A docu- 
ment tree is defined as the syntactic representation of a document when it is divided into 
subdivisions such as chapters and sections. A developmental tree is defined as a tree of in- 
formation obtained during the course of the development of a computer program. The task 
of documenting a computer program is then made equivalent to a transformation of its 
developmental tree into a document tree. When this transformation is performed by a com- 
puter program, the documentation can be achieved automatically. 

There is no attempt made in this paper to define the document tree more precisely. 
Only its tree structure is assumed. Efforts are concentrated on the developmental tree, 
specifically a subtree of it; the subprogram tree is illustrated in more detail. 

GENERAL APPROACH 

In the development of documentation programs, two objectives are paramount. 

Pieces of information about the program to be documented should be kept in a computer 
file during the development of the program, and this information should not be duph- 
cated in the file. The importance of the first objective is obvious; the information should be 
in a computer-readable form for documentation. The importance of the second objective 
can be seen whenever a change is made during or after the development of the program to 
be documented. One can easily make the mistake of changing information in one place and 
forgetting about it in the other place. On the other hand, a change of information at a 
certain place may require changes in other information. 

The goal of this project is to structure the developmental file of information in a tree 
structure (fig. 1 ) so that the nodes represent pieces of information. Any change in the 
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contents of a node may require changes in the 
subtree rooted in that node. In certain cases 
when the semantic structure is more complex, 
i.e., it may represent a directed graph, pointers 
may be used semantically. 

The final documentation of a program is 
produced from its developmental tree of in- 
formation. A special tree-traversing program, 
possibly interactive, selects out the contents 
of nodes or subtrees, invokes certain docu- 
mentation programs to transform these data into special format, and stacks this information 
sequentially. The sequentially stacked information is processed by a listing program to pro- 
duce the final printed document. 

Obviously the main problem is the establishment of the developmental tree structure. 

At this time, a complete tree structure cannot be proposed. The definition of certain types 
of subtrees, however, has been accomplished. One of these, a source program subtree, is 
described in detail. 



FLOWCHARTING AND PROGRAM LISTINGS 

Any large computer program should be segmented into subprograms, subroutines, and 
procedures. The size of a subprogram may depend on its complexity and on its source 
language. Documentation of a subprogram is usually done in three different forms: textual 
description, flowchart, and source language listing. 

The information should be structured as a tree. A source program is compiled 
(assembled), which generates a relocatable program. Figure 2 then defines the tree. 

Certain information such as size, entry points, and external references can be obtained 
from the compiler-generated relocatable program. The rest of the information should be put 
into the source program. Textual information can easily be placed into the source program 
by grouped comment lines. Thus the source program may be defined as a tree, as seen in 
figure 3. 

To combine the flowchart with the source program creates some problems. A special 


SOURCE 


S U .-i ? R a 6 R A ^ 

PROGRAM relocatable 


P K 0 G ^ A Vi 


Figure 2.— Tree structure for subprogram. 
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Figure 3.— Tree structure for source program. 
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form called a sequence chart is used. This is not a complete flowchart in the standard sense, 
but it forces a tree on the otherwise graph-structured flowchart. Then there is no problem 
in listing a tree structure sequentially. The missing links of the graph structure, which appear 
as transfer statements in the source program, can be implemented by semantic comments. 

A special computer program for a source language can automatically flag these places. 

Appendixes A, B, and C show the final printed forms of three different subprograms. 

The right side of the lists contains the actual program statements; the left side is stored 
internally as coded comments. The listing program takes care of this separation, but the 
actual sequential form is kept in the vertical direction. Those flow lines that represent the 
spanning tree of the program are shown with special characters, colons, periods, and aster- 
isks. The groups of textual descriptions are separated by horizontal lines of asterisks. Both 
the names of the groups and the characters used for line drawing are made flexible by changing an 
internal table in the printing program. Special print programs are available: A “level” print 
gives only those lines that are not indented more than a certain input parameter. A “selec- 
tive” print gives only a subtree; i.e., a defined group or a subtree of the body. The output 
of these print routines, formatted for a document processor, can be kept in the computer. 

This form of documentation has been very helpful in the project from which these 
three examples were taken. During the debugging stage, it was easy to follow the sequence 
chart to locate a specific segment of a subprogram without turning pages back and forth. 

Obviously, to get these forms, a good editing program capable of performing insertions 
and changes is needed. Appendixes D and E show appendix A in a developmental stage. 

In appendix D the initial sequence chart is defined. In appendix E an update procedure is 
shown. First the sequence chart is shown in a coding sheet geometrically; then its code is 
placed in front of it. The code for a line is composed by two fields. The first field defines 
either the depth of the text, 0 to 9, and blanks for program statements or contains special 
instructions, like group heading, change, and insert commands. The second field contains 
subcodes, such as line drawing codes for sequence charts and line numbers for updating 
commands. The text appears in the third field. In the actual input, the text field gets left 
adjusted. The lines will not be represented because they are already defined by codes. 

This procedure for writing a program has the following advantages: 

(1) It provides an up-to-date documentation of the program in the developmental 
stage. 

(2) It forces a programmer to lay out his program so that it provides an automatic 
documentation at any level. 

(3) It provides a form for a project leader to define subprograms without details that 
can be inserted by other programmers. 

(4) It may be used for the present-day coded flowcharting programs. 

Its main disadvantage is that it needs more work and discipline in the beginning. 

SUMMARY 

Printed documents have syntactic tree structures, such as titles, chapters, and sections. 
The semantic contents of the document may have more complex graph structures, but these 
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structures are implemented by semantic references. A computer program has a graph structure 
also, but a spanning tree on this graph can be defined with semantic references to the miss- 
ing links. This developmental tree of a program may have a different arrangement from a 
document tree. If the necessary information is contained in the developmental tree for the 
document tree, a transformation program can produce a document tree from the develop- 
mental tree. If the structures of the two trees are standardized, then this transformation can 
be achieved automatically. Otherwise, an interactive transformation routine can achieve a 
semiautomatic documentation. 



APPENDIX A-PRINTED SUBPROGRAM: EXAMPLE 1 


SUBROUTINE EXPRES (*» ISW) 

««»«*«*««***«**««*«***«««»»4i***«******«**««*«**««*j|i*4r« 

TITLE 

EXPRESSION translator, INFIX TO PREFIX 

•**••***•••*»••«********••*•••**•**•*•■**•*•*»*•••«•*« 

ABSTRACT 

AUTHOR; C.K.MES2TENYI 
*»* date; JULY 21, 1970 

«*• laguace: fortran s 

project: formal - subroutine 
search keys: none 

*••****«*•**•**«*•*•*•*•**•*•*••••>*>**••**••*»•*•****• 

DATA STRUCTURE . 

FORMAL.CMMN 

INCLUDE CMMN 

FORMAL. PWORD 

include PWORD 

*** argument: * ERROR RETURN 

ISW INPUT ARGUMENT 

w***************************************************** 

specification 

this is a generalized expression translation routine from 
INFIX to prefix form. IT ASSUMES THAT THE CALLING ROUTINE 
INITIALIZED THE SCANNER, THUS GSCANR GIVE THE CONSECUTIVE 
LOGICAL SYMBOLS. THE ROUTINE MAY BE CALLED FROM 4 DIFFERENT 
PLACES DEPENDING ON ISW; 

ISW = 0 PROCESS an assign STATEMENT: VARIABLE = EXPRESSION » 

= 1 TRANSLATE THE" EXPRESSION PART FROM A READ-IN DATA 
WHICH MAY BE IN THE FORM; EXPRESSION I 

OR variable = expression I 

= 2 PROCESS SUBSCRIPT EXPRESSION IN THE FORM; 

EXPRESSION ) 

S 3 PROCESS an expression IN THE FORM; 

EXPRESSION I 

IN THE FIRST CASE, THE INFORMATIONS FOR THE VARIABLE ARE 
STORED IN Nl,N2,N3. IN THE SECOND CASE, ONLY THE EXPRESSION 
PART IS retained UPON RETURN. IN ALL CASES. THE TRANSLATED 
AND SIMPLIFIED EXPRESSION IS PLACED ABOVE THE PUSH-DOWN 
STACK WITH the PUSH-DOWN STACK CONTAINING ONLY ONE ENTRY; 

A comma WITH A COUNT CORRESPONDING THE NUMBER OF 
EXPRESSIONS TO ACCOMODATE LISTS, 

»*♦••***••*•••**•**•*»•*»•»*•*•»»»*•**»»*••»•*••»•***» 

method 

AFTER INITIALIZATION, THE LOGICAL BCD SYMBOLS ARE OBTAINED 
BY GSCANR AND PROCESSED ONE-BY-ONE IN A LOOP, PROCESSING A 
SYMBOL IS DONE AS FOLLOWS: 

FIRST, IT IS CHECKED IF THE SYMBOL IS IN CORRECT TEXT) 

THEN 

constants- are linked in above the PUSH-OOWN STACK) 

VARIABLES - THEIR VALUES ARE OBTAINED FROM THE SYMBOL 
TABLE and linked ABOVE THE PUSH-DOWN STACK. 

IF THE VARIABLE IS SUBSCRIPTED, OR IT IS A' 

FUNCTION IDENTIFIER, THEN THE NAME IS LINKED 
IN ABOVE THE PUSH-DOWN STACK, AND A LEFT 
PARENTH. IS PLACED IN THE PUSH-DOWN STACK WITH 
COUNTsl. 
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LEFT PARENTH. - IS PLACED IN THE PUSH-DOWN 
STACK with COUNT=0. 

OPERATORS - THE PUSH-DOWN STACK IS EMPTIED OUT BY STkoUT 
UNTIL ITS TOP element HAS PRECEDENCE NUMBER 
EQUAL TO OR LESS THAN THE PRECEDENCE NUMBER 
OF THE OPERATOR. THEN THE OPERATOR IS PLACED 
IN THE PUSH-DOWN STACK. SIMPLIFICATION IS 

performed by STKOUT. 

RIGHT PARENTH., RICH BRACKET - THE PUSH-DOWN STACK IS 

EMPTIED OUT BY STKOUT UNTIL THE MATCHING LEFT 
PARENTH. IS FOUND. IF THAT HAS A COUNTrO. 

IT IS DISCARDED TOGETHER WITH THE RIGHT 
PARENTH. IF IT HAS A NON-ZERO COUNT, THEN IT 
INDICATES AN END OF SUBSCRIPTS (PAR.) OR END OF 
FUNCTION ARGUMENTS (BRACKET). IN CASE OF END OF 
SUBSCRIPTS, THE SUBSCRIPTS ARE COLLECTED AND 
THE value of THE SUBSCRIPTED VARIABLE IS 
OBTAINED FROM THE SYMBOL TABLE, WHICH IS 
LINKED IN. IN CASE OF END OF ARGUMENT LIST, 

THE FUNCTION IDENTIFIER IS OBTAINED AND LINKED 
IN 

SEMICOLON - INDICATES THE END OF EXPRESSION. THE PUSH-DOWN 
STACK IS EMPTIED OUT BY STKOUT. 


•••**••*••••«***•**•******* «****«*********•*« *****«««* 

LOCAL VARIABLES 


LOGICAL VARIABLE *SB' IS TRUE WHENEVER TH£ SCANNED SYMBOL IS 
IN SUBSCRIPT LEVEL. 'SBC VARIABLE CONTAINS THE DEPTH OF THIS 
LEVEL. 

LOGICAL variable 'EQL* IS TRUE WHEN AN •=< HAD BEEN PROCESSED 
already, thus it may not appear again. '=< MAY ALSO NOT APPEAR 
ON SUBSCRIPT LEVEL. 

THE SYNTAX OF EXPRESSIONS IS CHECKED AT EVERY SCANNED SYMBOL BY 
masking 'TEST' WHICH WAS SET BY THE PREVIOUS SYMBOL* IF THE RESULT 
IS NOT ZERO THEM THE EXPRESSION HAS SYNTACTIC ERROR. IN THE 
FOLLOWING TABLE, 'A' DENOTES AN ALPHANUMERIC NAME, 'N< DENOTES A 
numeric constant,'!' DENOTES POSITIVE INTEGER) 


SYMBOL MASKING BITS 

I (DEC.) 

RESET TEST 

(DEC. 

INITIAL ASSIGN 

. — 


1000000 

(64) 

INITIAL OTHERS 

— 


0100000 

(32) 

A 

0001110 

(14) 

0001000 

( 8) 

A( 

oooino 

(14) 

0100000 

(32) 

AC 

1001110 

(78) 

0100000 

(32) 

N 

1001110 

(78) 

0000100 

( 4) 

cn 

1001110 

(78) 

OOOOlOO 

( 4) 

III 

1001110 

(78) 

0000100 

( 4) 

( 

1001110 

(78) 

0100000 

(32) 

z 

lllOlOl 

(117) 

0000001 

( 1) 

UNARY ♦- 

1011110 

(94) 

OOlOOOO 

(16) 

BINARY ♦- 

1110001 

(113) 

0010000 

(16) 

* / ** 

lllOOOl 

(113) 

0010000 

(16) 

, 

1110001 

(113) 

OlOoOOO 

(32) 

) AS SEPARATOR 

1110001 

(113) 

0000100 

( 4) 

I 

1110001 

(113) 

0000100 

( 4) 

) AS END OF SUBS 

.1110001 

(113) 

OOOOOlO 

( 2) 
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moool ( 113 ) 


•BRT' AND 'PAR* ARE USED TO COUNT THE BRACKETS AND 
PARENTHESIS. RESPECTIVELY. 

logical 'NE(5' is set to true by For the next 
CHARACTER SCANNED ONLY, 


****»*••*•**•**••*«*•••«****«**•**«*«**•««***•***•**«* 

sequence chart 

INITIALIZE 

PUSH-DOWN STACK WITH COMMA 


I SUBSCRIPT LEVEL 



LOGICAL VARIABLES EOL AND END. INITIAL TEST 


GO To’sUBSCRIPT START IF ISWsZ 


LOOP TO PROCESS CONSECUTIVE SYMBOL 

• GET SYMBOL 

• BRANCH BY TYPE OF SYMBOL 

• t IND s 1,2, 3. 4 FOR 

• I INTEGER, REAL, IDENTIFIER, SPECIAL CHARACTER 


30 


.... INTEGER 

... real 

link in constant 


100 

110 

120 


change sign if neg is true 


... identifier 

CHECK is -1 factor SHOULD BE LINKED IN 

• • 

• • 

ERROR IF IT HAS MORE THAN 6 CHARACTERS 

branch by terminating character 


40 

50 


I 


I 


LOGICAL SB, EOL, neg 


NP=IG£TF1($990) 

NP0=NP 

C(NP)=20K10 

0(NP)=1 

SB= .FALSE. 

BRT = 0 
PAR = 0 
SBC=0 

EQL= ISW .GE. 2 
TEST=32 

IF (ISW .EQ. 0) TEST=64 
NEG= .false. 

IF (ISW .EQ. 2) GO TO 180 


CONTINUE 

CALL 6SCANR($990,IND,N1,ITC,ICC) 


60 TO (100,110,40,60) , IND 
1=0 

GO TO 120 
1=3 

IF (AND(TEST,78) .NE. 0) CALL FMLERR ( *990 , N1 , I , 1 ) 
TEST=4 

J=ILINK1(NP,I,N1) 

IF (NEG) D(J)=-D(J) 

NEG= .false. 

GO TO 30 


INEG = 1 
60 TO 500 

IF (ICC .NE. 0) CALL FMLERR ( $990 , N1 , 1 , 2) 
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... IDENTIFIER NOT TERMINATED DY ( OR t 


: : CHECK IF ITS VALUE MUST BE LINKED IN 

: i : 

t : J... NOf 6ET ITS NAME AS VALUE 


... YES. GET value FROM SYMBOL TABLE 
IF UNASSIGNED. THEN GET 
ITS NAME AS ITS VALUE 


COPY EXPRESSION AND 

LINK IT WITHOUT LEADING COMMA 


IS IT A LIST 

:... YES. empty push-down STACK' 
: COMBINE COUNT FOR COMMA 


LINK IN EXPRESSION 


... IDENTIFIER TERMINATED BY LEFT 

parenthesis : A( 


SUBSCRIPTED VARIABLE. LINK IN NAME 
AND PLACE '(• WITH COUNT 1 INTO THE 
STACK. INCREASE SUBSCRIPT LEVEL 


— IDENTIFIER TERMENATING WITH LEFT 
BRACKET ; AC 

GET FUNCTION IDENTIFIER. 

branch by type 


GO TO (130. ISO. 190). ITC -f 1 

130 IF (AND(TEST.m) .NE. 0) CALL FMLERR(S990.N1. 1.1) 
TEST=0 
N2=0 

140 IF (EQL .OR. SB) GO TO 160 

ISO IF (N2 .NE. 0) CALL ILINKl (NP.N2+7.N3) 

J=6 

IF (N2 .NE. 0) J=7 
CALL ILINKl(NP.J.Nl) 

60 TO 30 


160 CALL SYMBOL (5990.1) 

IF (EPTR .EG. 0) GO TO 150 


II=ICOPY0($990.EPTR) 

I=NEXT(II) 

J=LASTXX ( 5990 .11.1.0) 

IF (H2(II) .EQ. 1) GO TO 170 


CALL STK0UT(5990.16) 

IF (ITYP(NP) .GT. 17) CALL FMLERR ( 5990 . N1 , 1 . 1 ) 
D(NP)=D(NP)+H2(II)-1 

170 CALL RMOVFKII) 

call ILINKN(NP.I.J) 

GO TO 30 


180 IF (AND(TEST»14) .NE. 0) CALL FMLERR (5990 .N1 . 1 . 1 ) 
PAR = PAR+1 
TEST=32 


NP=ILINK1(NP. 17.1) 
CALL ILINKKNP.7.N1) 
SB= .TRUE. 

SBC=SBC+1 
GO TO 30 


190 IF (AND(TEST.78) .NE. 0) CALL FMLERR(S990.N1.1.1) 


l=IFUNCT(Nl) 


IF 

(I 

.EQ. 

0) 

GO 

TO 

210 

BRT 

= 

BRT+1 





IF 

(I 

.GT. 

1) 

GO 

TO 

200 


• • t 


DIFFERENTIAL FUNCTION 
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: ; 

right bracket j 

: END OF FUNCTION ARGUMENTS 


r 


NP=ILINK1(NP.23»0) 

GO TO 240 

NP=ILINK1(NP»21»0) 

HKNPjrl 
60 TO 240 

N2=0 

CALL SYMBOL($990t 1) 

BRT = BRT41 

IF (EPTR .EO. 0) GO TO 290 


I1=1COPYOU990.EPTR) 

IsNEXTdII 

J=LASTXX( 4990 . 1 1 . 1 > 0 > 
NP=ILINK1(NP« 22*0(11)) 
CALL ILINKN(NP.I*J) 
CALL IFREEini) 

GO TO 240 

NP=lLINKltNP»24(Nl) 


NP=ILINK1(NP*16*1) 

TEST=32 

GO TO SO 


60 TO (270. 260*290*270*300. 340*350*270*440*270*270. 270*390*400* 
1 420*270*270*270*270*430*270*460*460*410.270*270*270) *N1 

call FMLERR($990*N1*1*1) 


IF (AND(TEST*78) ,NE. 0) CALL FMLERR«S990 *N1 * 1 * 1 ) 


IF (TEST .EO. 2» GO TO 220 


INEG = 2 
GO TO 500 

CALL GSCANR($990, IND* IDT* ITCi ICC) 

IF (IND .NE. 1 .OR. IDT .LE. 0) CALL FMLERR(»990* ITC * 1 * 1 ) 

IrILINKl(NP,5*IOT) 
call 6SCANR(»990* IND. IDT* ITC. ICC) 

IF (IND .NE. 4 .OR. IDT .NE. 3) CALL FMLERR($990. ITC. 1. 1) 

TEST=4 
GO TO 30 

to 

L)J 
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f";! 


r ' 


(■ 


I 


r 


... RIGHT PARENTHESIS ) 

check' IP THIS IS AN END OF SUBSCRIPT 
OR the end of a SUBEXPRESSION 


I :... END OF SUBEXPRESSION. 

; : REMOVE MATCHING •(' 


... END OF A SUBSCRIPT LIST 
CHECK AND PACK SUBSCRIPTS 


CHECK IF THIS IS THE END OF 
TRANSLATION (ISW=2! 

;... NO. GO BACK TO VARIABLE PART 
i TO GET THE VALUE OF THE 

; SUBSCRIPTED VARIABLE 


290 IF (AND(TEST.113) .NE. 01 CALL FMLERR(J990. ITC. 1, I) 
BRT = BRT-1 

IF (BRT .LT. 0) CALL FMLERR( $990. ITC . 1 . 4 1 
TEST=4 

CALL STKOUT($990.17) 

IF (ITYP(NP) .NE. 16) CALL FMLERR 1 $990 . ITC . 1 . 1 ) 

1=0 (NP) 

J=NP 

NP=LAST(NP) 

CALL RMOVFlIJ) 

J=1TYP(NP) 

IF (J .LT. 21) CALL FMLERR($990. ITC. 1.4) 

IF (J .EO. 24) ITYP(NP)=I+24 

IF ((J .EO. 24) .AND. ((U24) .GT. 31)) 

1 CALL FMLERR($990.D(NP) ,1,3) 

IF (J .LT. 24) H2(NP)=I 
call STK0UT($990,21) 

GO TO 30 

300 IF (AND(TEST,113) .NE. 0) CALL FMLERR ( $990 . ITC , 1 . 1 ) 


PAR = PAR*1 

IF (PAR .LT. 0) CALL FMLERR ( $990. ITC . 1 . 4) 
call STKOUT($990.18) 

IF (ITYP(NP) .NE. 17) CALL FMLERR ( $990 , ITC . 1 . 4 ) 
IF (D(NP) .NE. 0) GO TO 310 


IsNP 

NP=LAST(NP) 
CALL RMOVFKI) 
TESTI4 
60 TO 30 


310 TEST=2 

N2=0(NP) 

IF (N2 .GT. 4) CALL FMLERR ($990 ,N2. 0 , 5) 

N3=0 

SBC=SBC-1 

IF (SBC .EO. 0) SB= .FALSE. 

DO 320 KK=N2-1.0.-1 
K=NEXT(NP> 

IF (ITYP(K) .NE. 0) CALL FMLERR ( $990 ,D (K) , 2, 13) 

IF (D(K) .LT. 0 .OR. 0(K) .GT. 511) CALL FMLERR($990.0(K) .0. 15) 
FL0(9»KK,9.N3) = D(K) 

320 call RMOVFKK) 


IF (dSW .EO. 2) .AND. (.NOT. SB)) GO TO 330 


J=NEXT(NP) 

N1=0(U) 

K=NP 


r 
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YES. RETURN FOR ISW=2 

MINUS 

SET 'NEG= and LINK IN ♦ 

PLUS + 

IS IT UNARY OR BINARY 

; unary plus or minus 
:... BINARY + - 

COMMON PART FOR BINARY OPERATORS 


MULTIPLICATION * 

00 TO* BINARY OPERATOR 
EXPONENTIAL »* 

00 To'oINARY OPERATOR 
DIVISION / 


GO TO BINARY OPERATOR 
SECOND ENTRY 


left parenthesis 


GO TO CHECK FOR -I FACTOR 
COMMA* 

EOUAL*SIGN = 



NP=LAST(NP) 

CALL RMOVFN(K.J) 
GO TO 140 



330 

CALL IFREEOINPOI 
RETURN 



340 

NEO= .TRUE. 



350 

IF (AND(TEST.94) .NE. 0) 

GO TO 

360 


CALL STKOUT(S990.18I 

TEST=16 

GO TO 30 



360 

J=18 



370 

380 

1 = 2 

IF (ANDITEST.113) .NE. 0) 
TEST=16 

CALL STKOUT(S990, J) 
NP=1L1NK1(nP.J.I) 

GO TO 30 

CALL 

FMLERR($990.1TC.1.1) 

390 

U=19 




GO TO 370 



400 

J=20 




GO TO 370 



410 

l=-2 

J=19 




GO TO 380 



420 

IF tAND(TEST.78) .NE. 0) 
PAR = PAR+i 
TEST=32 
INEG = 3 

CALL FMLERRt 1990. ITC. 1.1) 

425 

GO TO 500 
NP=ILINK1|NP.17.0) 
GO TO 30 



430 

IF (AND(TEST.n31 .NE. 0) 
TEST=32 

CALC 5TK0UTtS990.16) 
0(NP)=0(NP)+1 
GO TO 30 

CALL 

FMLERR(S990.ITC.1.1) 

440 

IF tAND(TEST.117) .NE. 0) 
TESTrl 

CALC 

FMLERR(*990.ITC.1.1) 
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GET AND CHECK VARIABLE FOR ASSIGN 
statement save info, in NN1.NN2.NN3 


GO BACK TO translate EXPRESSION 


... SEMICOLON I 

... APOSTROPHE ' 

GO TO END OF TRANSLATION 


END OF LOOP 


IF (EQL .OR. SB) CALL FMLERR ( S990 , ITC . 1 . 1 ) 
EQL= .TRUE. 

CALL STKOUT($990. 18) 


IF ((ITYPINP) .NE. 16) .OR. (D(NP) ,NE. 1) .OR. (LAST(NP) .NE. )) 
1 call FMLERR(S990.ITC.1.1) 

KK=NEXTINP) 

IF (ISW .EO. 1) 60 TO L50 

IF UKK .EO. 0) .OR. (ITYP(kK) .LT. 6) .OR. (ITYP(KK) .GT. 7)) 

1 call FMLERR(S990.ITC.1.1) 

NN1=D(KK) 

NN2=0 

IF (ITYP(KK) .EG. 6) 60 TO 450 
NN3=NEXT(KK) 

NN2=ITYP(NN3)-7 

NN3=D(NN3) 

450 call IFREEO(KK) 

NEXT(NP):0 

60 TO 30 


460 IF (AND(TEST.113) .NE, 0) CALL FMLERR ( *990 . ITC . 1 . I ) 


END OF translation 


RETURN FOR 'ISW = 1 AND 3 
I 

TRANSFER ASSIGNED VARIABLE INFORMATION 


RETURN FOR 'ISW =0 

CHECK IF -1 FACTOR MUST BE INSERTED 
INDICATED BY 'NEG' 

:... NO. GO TO RETURN TO CALLING PLACE 
:... YES. LI)<IK IT IN 


RETURN TO CALLING PLACE 
ERROR RETURN 


IF (PAR .NE.O .OR. BRT .NE.O) CALL FMLERR t *990 .'{ ) C3'.1.4) 

call STKOUT (*990. 18) 

IF ((ITYP(NP) .NE. 16) .OR. (LAST(NP) .NE. 0)) 

1 CALL FMLERR(t990,ITC,l,l) 

IF (ISW .NE. 0) RETURN 

IF (.NOT. EQL) CALL FMLERR (*990 , ITC , 1 , 1 ) 

N1=NN1 

N2=NN2 

N3=NN3 


RETURN 


500 IF (.NOT. NEG) GO TO 510 

NP = ILINKKNP.19.2) 

CALL ILINKKNP.O.-I) 

neg = .false. 

510 60 TO (50.265,425) t INE6 

990 CALL IFREEO(NPO) 

RETURN 1 


END 
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APPENDIX B-PRINTED SUBPROGRAM: EXAMPLE 2 


m************M*»**^i****'^******^* ****■$**** ^L**********itm 

TITLE 

MAIN PROGRAM FOR INTERACTIVE FORMAL SYSTEM 


**^*if****m^^ti**t **9* ********************* ************* 

SEQUENCE CHART 

INITIALIZE BY CALLING FMLOPT 
LOOP TO GET next INPUT LINE 

• read line 


IF IT starts with «C • (COMMENT). GO TO GET NEXT 
LINE 

IF It'sTARTS with *P • (PRINT). GO TO 'P ' ENTRY 


LOOP TO GET statement TYPE IN J 

* 

* 

END OF LOOP 

J=0. IT IS AN ASSIGN STATEMENT 


reprint ERASE. option. ROLOUT. save ANO RESET 
STATEMENTS 

« 

4 

* 

BRANCH By type 

READ statement 

print statement 
: 'P • = print 


. .. DUMP statement 


ERASE 


STATEMENT 


parameter IDIM = 10- 

DIMENSION IN(14). INN(14). ITAB(IDIM) 
equivalence (IN(2). INN(D) 

DATA INN(14) / •)' / 

DATA ITAD /’READ PRINT DUMP ERASE OPTIONCOMMEN' 

♦ . 'roloutncountsave reset '/ 


99 CALL FMLOPT (MNTI'.O) 


110 READ 100. END:200. IN 
100 FORMAT (13A6.A2) 


IF 

(FLD(0,12. IN( 1) ) 

.EQ. 

1005K) 

GO 

TO 

no 

IF 

(FLO(0, 12. IN(1) ) 

.EO. 

2505K) 

GO 

TO 

22 


J = 0 

DO 111 I r I.IDIM 

111 IF (IN(1) .EQ, ITAB(D) j = I 


IF (J) .60. 

60 TO (121. 121. 121. 120. 120. 110. 120. 121. 120. 120). J 


120 CONTINUE 
PRINT 101. IN 

101 FORMAT (XA6.' ! ’.13A6) 

121 GO TO (1. 2. 3. ’4. 5. 110, 7, 6, 9. 10). J 

1 CALL FMLIOI ( INN.O) 

GO TO no 

2 call FMLI02 (INN.O) 

GO TO 110 

22 FLO(0.6.IN(1) ) = 0505K 

CALL FMLI02 ( IN, 0) 

GO TO 110 

3 CALL ONOMP 

K '= 'P* 

IF (INN(I) .NE, ' ') X = 0 
CALL OUMP(K) 

call OFFOMP 

GO TO no 

4 CALL FMLERS (INN.O) 
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... OPTION statement 


60 TO 110 


• 

5 

CALL FMLOPT (INN, 0 


... rolout statement 


GO TO no 



7 

CALL FMLOUT (INN.O) 


... NCOUNT statement 


60 TO 110 


• 

a 

CALL COUNT 


... SAVE statement 


GO TO 110 



9 

CALL FMLSAV (INN) 


... RESET statement 


60 TO 110 



10 

call FMLRES (INN) 

• ASSIGN statement 


GO TO 99 

* 


60 

PRINT 102, IN 

* 


102 

FORMAT (X14A6) 

• 



CALL FMLASG (IN,0) 

« 

END OF FILE READ - STOP 


60 TO 110 

* 

*t*«***«*«4(«**«« **»«**«««****»»***«*«■**«« ««*****«***#« 

200 

STOP 

ENO 
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APPENDIX C-PRINTED SUBPROGRAM: EXAMPLE 3 


title 

COMMON 0*TA structure TOR FORMAL SVSTEM 


OaTA STURcRUC 

arranged in ) labeled commons 

USED AS PROCEDuRCi INCLUDED IN OTHER SUBPROSRAMS 


It LINKED storage AREA 

• The corresponding cm«Diii sords are always 

• used in Pairs for storing an itemi 

• The oime'>s1on of c«oi coimi may be Changed 

• during P'STALLATIONt 

• fields in The c-o words depend on the usagei 

• They are iiEFineO bT procedure 'PWORO»t generallt* 

• The last |S bits in C is used for linkage OF 

• LINEAR ARrAYSi 


2t common block for indivioual pointers ano switches 

FREE (available) STORAGE |N C«0 

• ClN*N*NAl "FIRST 

• C ( |L ILIL ) • LAST location 

• the linear array is linkeo in The 

• last is bits of TmE C**OROSt 

• 1 

•ttt SYMBOL table with TREE STRUCTURE IN R LEVELS 

• stored in C-O AREAt FIELDS IN THE C-WOROt 

• ITTPB • last • next 

• NS • first entry in CINSI-oINSI 

• » 

• NSB • Subroutine level pointer 

• 1 SUBPROGRAMS are in ALPHABCTIC ORDER 

• 1 

• ltttlTYP8(NSBl*0 

• ittt O(nSB) • alphanumeric name of the 

• 1 SUBROGRAM 

• i.tt NSY • lastinsbi pointer to stmbol entrt 

• ! I symbols are in alphabetic order 

• ( I NSYl • POINTER TO PRECEEOING SYMBOL 

• 1 i Entry 

• I I 

• I Ittt oInsyi . alphanumeric name of The 

• I I symbol 

• 1 ittt ITTPBInSTIr type of SymBOLi 

• ill SEE table It 

• t I Ittt >ji. indirect reference 

• III LASTInSTI points to an OTHER 

• III symbol 

• I ! I 

• I I im second And third bit • ii 

• III subscripted variable 


chhn PROC 


implicit INTEGER(A»Z) 
parameter error - ERRERR 


parameter coin • 20RB 

COMMON /FMLCM2/ ClCDIHl 
COMMON /FMLCMJ/ O(CDIM) 

COMMON /FMLCMI/ 


* NXnXNXi ILILiL 


NS, 


NSBl 


♦ NSy.nSYI, 
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r 

I 


l 


r 


I i : Nsu " l*st(nsy), pointer to 

; ! i 1 SUBSCRIPT Entry 

I t I I SUBSCRIPTS are ORDEREO By 

I : I I NUMBER OP SUBSCRIPTS! PNC 

I I I I BY actual SUBSCRIPTS! NSUI 

I I I I • POINTER To PRECEEDINO 

t t t ( svescRtfr entrt 

ill; * nsuinsui, 

I : I III! BlNSUI • numeric SUBSCRIPTi 

1 I t I SEE TABLE III 

I : I liii FIRST 3 BITS OF CINSUI* 

I I I I tl!i MllOi UNASSISNEO. 

I I I i I INDIRECTLY REFERENCED 

I I I I » LASTINSUI POINTS 

I i 1 1 ) To OTHER symbol 

I I ; i > Entry 

i I I I I I I I • I I I I last SUBSCRIPT 

I I I I ; ENTRYi 

I I I I I LASTINSUI Points 

i ! I I I back to its 

I I I I I Symbol • nsy 

till till •010, normal entry 
I ; I I t LASTINSUI points 

I I I I t To expression 

I i I i I value • EPTR 

I S I III! nEXTINSUI ■ FORYIARD LINK TO 

I i I NEXT SUBSCRIPT iZERO FOR 

I ! I The LAST ONE 

I I III, OTHERS. LASTInSYI • EPTR 

I ! EPTR « expression pointer 

III ♦ EPTR, 

I i i.ii ITYPBIEPTRI • 16 

i i i 1 1 1 last IEPTr I . 0 

i i ill, hJIEPTMI ■ number of 

I : I EXPRESS lOHS IFOR LlSTSI 

: I i 1 1 1 .( I I lPtu I • 

i • i -.a. Expression is In 

i : : : core 

: I ; III. NOT TERO, EXPRESSiUN 

II i IS ON QRIJM 

! I InoE* • hKEpTri 

; i III! N-: XT I ►, P f 0 ) F ONRXNO LI NK 

I : i.i T.-if; linearly stored 

! i EXPRiSjlON ,vmEN it IS 

: : 00 COR-IiT.I;; CONSECUTIVE 

; I Kor'iics .iRF iCCOroing 

: 1 T J TARI-E Ml, 

: III, Nt'XTINSYl • FORRARj link 10 NEXT 

1 STi.UOL, XERO FOR LAST ONE 

ill! NEXTIN30I • fOR/.ARO link To next 
SUBPRO'.RAM i ZERJ FOR LAjT onE 

Temporary variailes for 

Ni • name of a variable 

n2 * number of subscripts 

N3 • subscript aoRO 

IT • 3 OR I FOR SUBSCRi OR NOT 



r 
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Nl iN2 tN3 > I T I 


... OPTION S*iIChES 

JOTOpT • OPTION *nPO PNOM »*5T STATEMENT 
PROOE* • £<P«NO POAERS OVER PROOUCT 
iNT&sp • evaluate integer valued PUNCTIONS 
PArNsR • E'VALUAr.: f<rNLV<rfCAL ruvcrfavs 
EAPCs* ■ USE DISTRiauTlVE l** 

P0*ER • EXPAND 5U“S RAISED TO POS. INTEGERS 
BASE • OiliJ.D ECR aASEIOl|l2I.IIOI.(El 

... MISCELLANeCUS 

SIPPSA « USED BT STOUT ROUTINE POR RECURSIVE 
SIHPlIFICATION 

bits* • USED BT STOUT ROUTINES 
lOUNlT A I/O UNIT- NUnRER |P 1/3 STATEMENTS 
ETRArO a NUMBtH OP PORTRAN TYPE ARGUMENTS 
CEPARt ■ number op APOJ RENTS IN A OEPINEO 
PUNCT ION 

OEPFUN a j If OEPIMD FUNCTION, o FOR VARIABLE 
NK a start Of ARCUI-ENT CMAIN In'c-0 FOR LtsT 
OF VARIABLES 
CBUP • I/O BUFFER 

NP • PUSH-OOAN STACK pointer |N C-0 AREA 


XOfoPT.PRODEx , lNTSS#iNATHSIf,E«POS»,PO»£RiBASE i 


♦ SlMPSA.BlTSN, lOUNIT ,FTRAR6,DEFAR5|0EFrUN,NK,CBUP|NP 

logical int gs a.Naths*. power. s imps* •B lTSRlI’ROOE* 
REFERENCES ON 

ENO 
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APPENDIX D-DEFINITION OF INITIAL SEQUENCE CHART 


Coding Form 

The coding form is divided into three fields: Field 1 consists of one character, the 
general directive for input; field 2 contains special directives for flowchart elements and 
label for program statements; field 3 contains the text. 

An initial program is illustrated below: 


T 

S 

OD 

ID 

2B 

2B 

2B 

2BE 

0 

0 


EXPRESSION TRANSLATION 
INITIALIZE 

LOOP TO PROCESS CONSECUTIVE SYMBOLS 
BRANCH BY TYPE OF SYMBOL 
l-INTEGER 
-REAL 
-IDENTIFIER 
LsPECIAL CHARACTER 
END OF LOOP 
END OF TRANSLATION 
END 


Input Form 

The actual input does not contain the lines; the text is left adjusted in field 3: 

T EXPRESSION TRANSLATION 
S INITIALIZE 

OD LOOP TO PROCESS CONSECUTIVE SYMBOLS 
ID BRANCH BY TYPE OF SYMBOL 
2B INTEGER 
2B REAL 
2B IDENTIFIER 
2BE SPECIAL CHARACTERS 
0 END OF LOOP 

0 END OF TRANSLATION 

END 

Output Form 

The initial program can be listed with line numbers as follows: 

1= EXPRESSION TRANSLATION 

****************************************** 

SEQUENCE CHART 
2= INITIALIZE 
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3 = LOOP TO PROCESS CONSECUTIVE SYMBOLS 
4=: BRANCH BY TYPE OF SYMBOL 

5=: INTEGER 

6=: :...REAL 

7 = : IDENTIFIER 

8 = ; SPECIAL CHARACTERS 

9= END OF LOOP 

10= END OF TRANSLATION 

11= END 


APPENDIX E-EXAMPLE OF AN UPDATING PROCEDURE 


+1 

+R7D 

IB 

IB 

1BE 

+R8D 

IB 

IB 

IB 

IB 

1BE 


SUBROUTINE EXPRES {*. ISW) 

-IDENTIFIER NOT TERMINATED BY ( OR [ 
-IDENTIFIER TERMINATED BY ( 
-IDENTIFIER TERMINATED BY [ 


NEG = TRUE. 
- + 

J = 18 

J = 19 

J = 20 

L/ 

J= 19 
I =-2 


Note that the ‘+’ is an insertion directive. The number following + indicates the line 
where the insertion is to be done. ‘R’ indicates that the levels of lines following to be in- 
serted are defined relative to the line where the insertion occurs. 


DISCUSSION 

MEMBER OF THE AUDIENCE: I notice that you have many comments noted through 
there. It seems to be about a two-to-one comment per statement. Is that about correct? 

MESZTENYI; It depends on the program. It depends on the language, too. The com- 
ments should be semantic, not repeated as an equation. 

MEMBER OF THE AUDIENCE: Do you think that some of the discussions about what 
we can get out of the compiler would fall into this? 

MESZTENYI: I would like to have the compiler in the subroutine. I would like to do 
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that, but I would start here from the development point first, because this is where one 
defines the program first. 

MEMBER OF THE AUDIENCE: It seems that the compiler could give you certain in- 
formation, and you could add some personal comments and have better descriptive material. 
Is that true? 

MESZTENYI: It depends on what standpoint you look at. As I look at it, I want an 
overall view from the beginning. Before I finish the program, I might want to give the speci- 
fication a bigger flowchart type of definition that could be used right away. 

MEMBER OF THE AUDIENCE: You are trying to get the flavor of the program that 
you are working on for a certain purpose. The compiler will only come out with standard 
words for any program. The compiler does not know what your program is, but you do. 

With personal comments added to the program, what you have would provide additional 
information. 

MESZTENYI: I find it is hard for programmers to add something after they have 
written the program. When they write, they do not mind writing down their comments. 

MEMBER OF THE AUDIENCE: I am working from the viewpoint that we now have 
difficulty at times getting any comments in, and if we provided a lead into the comments and 
they went down the list and it did not make too much sense to them from a general view- 
point, that they could add these rather well. 

MESZTENYI: I agree tliat they could, and this is actually what is now done. I added 
this myself. 

Tlie other part I would like to focus on a little bit is the programming part. If you start 
from the sketch with those lines coming down and write, you make the programmer apply a 
little discipline to the subject of program placement. For example, I try to avoid any 
GO TO unless it is some kind of loop structure. I try to avoid going back. I find a loop for 
each logic curve that I process, but it is not a DO statement, and I jump directly back to 
the beginning. It probably would have been much nicer documenting it to go to the end of 
this loop and comment it, which goes back and gets the next one. In this way it forces the 
programmer to do a documented description because it is very hard to document a graph 
that points out the actual information. The text or the description of the program is 
sequential, but semantically it is a graph. A tree, which is sort of in-between, is much easier 
to represent. You have cross-references, but the form is still a tree, and this is what I tried 
to simulate. 

MEMBER OF THE AUDIENCE: I think the speaker is trying to get the programmer 
to write down what is being accomplished and when. Once in the right-hand side, the lan- 
guage does not really matter. He is trying to read narrative text so that you get some con- 
cept of when things happen and what really is happening because the specification of the 
problem is written in a narrative form. He does that rather than deduce what was done from 
how something is being done. I do not think a programmer is going to do that very well 
because he is so involved in the mechanics that he cannot get out of them. 

MEMBER OF THE AUDIENCE; It seems to me that here is a case where we can go 
from the rationale of a subroutine and in an automated way feed in the programming lan- 
guage statements. Is this what you had in mind? I could see how you actually tried to 
develop your subroutine. I can see how you can start with the rationale of the subroutine 
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first and then by using the type of coding that you did, you could automatically call for the 
appropriate programming language statements. 

MESZTENYI: Not automatically. I certainly think of more than just the semantic 
type of description that I want to accomplish. What I want to accomplish eventually is the 
statements. 



